Skip to content

spec(FIX-1430): manager-queue lab — the proof that work reaches a seat - #1919

Closed
jhoffner wants to merge 3 commits into
mainfrom
spec/FIX-1430
Closed

jhoffner wants to merge 3 commits into
mainfrom
spec/FIX-1430

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 19, 2026 •

Copy link
Copy Markdown
Collaborator

spec(FIX-1430): the proof that work reaches a seat

Someone who… Today After
has a declared team and work to hand out Hands it out one dispatch at a time, from code. Nothing shows what waits or who holds it Files rows on the team's channel board, names who each is for, watches a queue
asks whether routing actually works Two halves, proved alone and never together: a post reaching seats declared in Markdown, and a board row becoming a real run over a board written in TypeScript One run, one tree of Markdown: a coordinator files, the board routes, three seats work
wants to see what the team is waiting on Reads raw rows and counts them Four columns — queued, running, waiting on you, done — each computed at read time, none stored
files more work than the team has seats No shared queue to file it on Rows wait, holding the seat they were filed for. Nothing is lost, nothing is re-routed
wires a board for a team today Forty-odd lines of TypeScript per team, the ledger declared twice so the claim gate passes One line in the channel's file. The old shape stays next door, so the two stand side by side

Today and after, side by side. Today a team's board is about forty lines of TypeScript declared twice, once on the coordinator flow and once on the recipient so the claim gate passes, with one assignee key, one row, one hand-off and no queue. After, one boards line in the channel's own file mints the ledger, a coordinator seat files four rows through the task tools its own file grants it, and rows route by assignee to three declared seats while a fourth waits behind a busy seat; four queue columns sit below as a read-time view over rows that already exist.

Left is what a team writes today, and it is code. Right is the same team written as files, with one more row in flight than there are seats to run it — the case the columns exist for.

How: a lab under goals/, not a surface. A tree of Markdown declares one channel holding one board, a coordinator seat and three worker seats. The coordinator files four rows through the task tools its own file grants it; the rows route by assignee; the fourth waits behind a busy seat. The queue columns are computed from rows that already exist. This issue owns ER-20, the epic's exit gate, and owns nothing else.

Need your sign-off

Open · does the exit gate close on routing proved, or on routing proved all the way into real work?

In plain terms. Either the demo ends at the right worker picked up the right job and reported done, or it ends at the right worker picked up the right job, and here is the file it changed.

The trade-off. The narrow reading makes the gate fast, deterministic and rerunnable on every change — but an outsider reading work reaches a seat that runs it may reasonably hear the wider one. The wide reading is closer to the words and costs a check that takes minutes, needs a scratch repository and a live harness, and fails for reasons unrelated to routing. A gate that goes red for unrelated reasons stops being one.

My recommendation: the narrow one, with worker seats doing small real work — writing a file the check reads back — rather than nothing. goals/devforce-lab/ already shows a board row becoming a supervised coding run. What has never been shown is a queue crossing from a declared coordinator to declared seats, and that is the gap this issue was adopted to close.

What would change my mind. If the promise will be read publicly as declare a team in Markdown and it ships code, the two halves have to meet in one run at least once, and this is the cheapest place to make them meet.

What being wrong costs. Narrow when it was wide: the epic wraps on a claim narrower than it reads, and someone builds the wide check afterwards — a few days, nothing already built thrown away. Wide when it was narrow: the gate is slow and intermittently red from the day it lands, which is worse because it is permanent.

Ratified, for confirmation

  1. D1 · The lab ships no package code — the queue columns stay lab-local. If wrong: a view surface is designed from one example, exported, then redesigned when a second consumer disagrees.
  2. D2 · The proof is a queue, not a hand-off: more rows than seats, the coordinator assigning through the tools it declared. If wrong: we re-run FIX-1385's own check with an extra seat, call it the exit gate, and prove the half of ER-20 nobody doubted.
  3. D3 · What a busy seat does is shown, not chosen: the lab is wired to run at either drain width, and the comparison goes to the epic when it asks for it. If wrong: a lab settles a policy the epic owns, in a folder nobody reads as a decision.

Number 2 is the one to weigh — it is what separates this from a second copy of a check that already exists. Reasoning and what lost: DECISIONS.md.

Reviewers · look here

  • Plan → what this consumes. FIX-1430 takes neither FIX-1394's contract nor its implementation as a build input — only ER-2 as a fence on what the lab may author. If that reading of ER-2 is wrong, the dependency edge in the epic needs re-drawing, not adjusting.
  • Decisions → D2. Is the delta against FIX-1385's own goal check real? Its acceptance criteria already claims to stand the exit gate on its surface. If a third seat on that check would do, this issue is redundant and should be closed.
  • Rules → BR-10 and BR-11. The columns are a read. Idle is the absence of a live claim, not a stamp. Easy to test wrongly, and a view that writes anything is the failure ER-11 exists to prevent.

Not here: the nested personal/request cascade (phase-2 inside W4, off this gate), any apps/docs page (the epic's docs pass owns ER-22), and any change to a published package.

Spec · Decisions · Rules · Plan · Linear FIX-1430 · epic FIX-1407 · builds on FIX-1385 · never merges

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction document in four files, not an implementation. Reviewing it well means answering one question: is this the right approach?

In scope to challenge:

  • The problem framing in SPEC.md — are we solving the right thing, for the people named?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label or a colour you'd have chosen differently is not a finding; a figure that shows a shape the decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch showing the shape of the proposed solution. It is knowingly incomplete, is not real code, and is not what will ship. Review it for directional viability only. Do not report that it lacks error handling, omits edge cases, names things that don't exist in the repo, or wouldn't build: all of that is true on purpose.
  • Any POC files on this branch, entirely. This PR is never merged, so it may carry throwaway proof-of-concept code, characterization tests, or an HTML mockup built to validate the direction. None of it ships. Read it to judge whether the shape holds; do not review it as code.

One request, if you are an automated reviewer: the two lists above are the whole difference between a useful review of this document and a long one. Volume is not signal here — a single finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback about their direction is not line-level and is treated like any other above-the-bar finding.


Generated by Claude Code

``<source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/RetriggerDark.svg?v=2"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2"><img alt="Retrigger" src="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2" align="right">``Confidence Score: 2/5

The direction should not be approved until the busy-seat contract is made internally consistent, routing is constrained before claims, and recoverable lapsed work remains visible in the queue.

Findings

  1. &lt;img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=9" align="top"&gt; Busy-seat rules conflict ▶
  2. &lt;img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=9" align="top"&gt; Drains can claim wrong rows ▶
  3. &lt;img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=9" align="top"&gt; Recoverable work disappears ▶

Summary

This PR defines the direction, business rules, and implementation plan for a Markdown-declared manager queue lab.

  • It proposes a coordinator, three worker seats, a shared channel board, and four derived queue columns.
  • The current documents conflict over whether busy-seat behavior is prescribed or merely compared.
  • The per-seat shared-ledger drain shape can claim work before assignee routing.
  • The queue predicates omit recoverable in_progress rows whose lease has expired before child adoption.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  C[Coordinator files four rows] --> L[(Shared ledger)]
  L --> A[Seat A drain]
  L --> B[Seat B drain]
  L --> D[Seat C drain]
  A --> X{Claim occurs before assignee routing}
  B --> X
  D --> X
  X -->|wrong seat claims row| R[Routing refusal or failed row]
  L --> H[Hand-off]
  H --> E[in_progress row with expired lease]
  E --> M[Missing from all four columns]
  E --> I[Addressed seat shown idle]
Loading

Reviews (1) · Last reviewed commit: "spec(FIX-1430): manager-queue lab — the ..."


Generated by Claude Code

Four documents and two figures at spec/FIX-1430/. The fifth and last
first-cut child of FIX-1407 (W4), and the owner of ER-20 — the epic's
behavioural exit gate.

A lab under goals/, not a surface: a coordinator seat files rows on a
channel's board and assigns them to three declared worker seats, with
queue columns derived at read time over rows that already exist.

Three decisions: the lab ships no package code; the proof is a queue
rather than a hand-off; what a busy seat does is shown, not chosen.
One open question, on how much realism the exit gate closes on.

Written against landed code at d8e4c99 and against the board surface
FIX-1385 is specifying. Consumes FIX-1394's ER-2 only as a fence —
neither its contract nor its implementation is a build input.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
@vercel

vercel Bot commented Sep 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 19, 2026 11:21am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 19, 2026 11:21am UTC
flow-state-dev-ui Ignored Ignored Preview Sep 19, 2026 11:21am UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 19, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-19T03:41:50.027728Z 3c51400 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@linear-code

linear-code Bot commented Sep 19, 2026

Copy link
Copy Markdown

FIX-1430

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — coherence on this never-merge child-spec, after its ER-15 raise on the epic (#1905).

Not owner approval / not the gate. Shared jhoffner login looks like Jake; product sign-off on Q1 / D1–D3 stays with Jake (and PM on kill/over-scope).

Coherence vs W4

No silent two-direction fork against #1905, #1915, #1916, or #1917.

  • D1 (lab-local columns, no package export) matches ER-11 / "proof consumes, does not own surfaces."
  • D2 (queue ≠ hand-off; more rows than seats) is the real ER-20 delta vs FIX-1385's one-row VG — keep that sentence; it is what stops this issue from being a redundant third-seat re-run.
  • D3 (show both busy-seat widths; comparison goes to the epic) matches the Open table settler for auto-scale / busy-copy and ER-15. Do not pick a drain width in goals/.

Reuse-vs-create: report the knob you ran; do not rule. If FIX-1385's review settles it first, follow that ruling.

Soft note (already on the epic)

FIX-1385 AC saying it "is the exit gate" and ER-20 owned here can read as two owners. Complementary halves (surface vs queue proof) — epic fold asked to name the split; leave D2 as written.

Open for Jake

Q1 (narrow routing-proved vs wide harness-backed coding) stays unsettled here — Architect lean later if asked; not closing it from this stamp.

— FSD Architect

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (spec-only)

Verdict: direction is right; scope is heavier than the exit gate strictly needs. I would not block merge on architecture — D2 (queue with more rows than seats, coordinator filing through declared task tools) is the correct answer to “don’t quietly re-run FIX-1385’s hand-off,” and D1 (lab-local columns, no package export) matches ER-11 and keeps W4 ship fences clean. The planned lab shape (pentest host + refusal twins + devforce contract/goal split, queue.mts as a pure read over existing task rows) reuses established goals/ patterns instead of inventing a framework surface — that part is a good sign, not a smell.

Where the approach went further than necessary is mostly bundling, not wrong forks:

  1. ER-15 drain-width evidence (D3 / S8 / V5 / BR-17) in the same issue as ER-20/21 — Policy (“don’t pick width in goals/”) is well argued; requiring two full queue runs in the same acceptance bar as the epic exit gate doubles moving parts and (if S8 reuses the model-backed coordinator path) roughly doubles flake budget. Cleaner alternative: keep D3 as a decision fence in this spec, ship one runnable queue for FIX-1430; record the width comparison in a tiny follow-up issue or an epic-owned script invoked when walls are ruled — same evidence for ER-15, smaller FIX-1430 implementation PR.

  2. Contract gate breadth (S5–S6, BR-1–3, 8–9, 13–15) — Pentest/devforce parity is understandable, but much of this grades fences and hygiene, not what makes the epic sentence true. Cleaner alternative: minimum bar = hire tree + queue.mts before/after read (BR-10) + VG for BR-4–7; treat refusal twins as “match pentest if cheap” (one twin, not two) and drop BR-9 from the rules table (keep the observation in DECISIONS only).

  3. Narrative duplication — ER-20/21 acceptance, column semantics, and D2 rationale appear in SPEC, BUSINESS-RULES, DECISIONS, PLAN sketch, plus the-view.svg, mermaid in BUSINESS-RULES, and what-changes.svg. Cleaner alternative: one canonical acceptance block (BUSINESS-RULES), one column diagram (the-view.svg or mermaid, not both), SPEC sign-off points at decisions without re-deriving.

  4. Q1 still open at sign-off — Recommendation already points at narrow workers + small real work; PLAN/VG don’t yet hard-require stub workers, poll/wait fixtures, or “contract files rows / goal only grades assignment” mitigations. For a spec gate, I’d close Q1 as narrow (even one line) so implementers don’t drift toward devforce-scale harness ×4.

Third-party / reuse: No missing package — there is no orchestration “queue view” to import; lab-local S4 is spec-correct. Reuse pentest org-wrap for BR-8 and pentest refusal-tree mechanics; avoid a third readLabTree (FIX-1405). BR-14 goals-only diff check is new CI surface — fine, but it’s net new complexity worth calling out in the implementation PR.

Skipped (would need implementation PR): whether contract gate batches openLab, exact FIX-1385 landed API names.

Approval: Not approving yet — not because D2 is wrong, but because S8+V5 on the same bar as VG and unsettled Q1 are the two places a simpler spec would save the most cost without weakening the exit gate. If you split or defer S8/V5 and nail Q1 to narrow in SPEC sign-off, I’d be comfortable approving the spec as-is on direction.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread spec/FIX-1430/PLAN.md Resolved
Comment thread spec/FIX-1430/PLAN.md Resolved
Comment thread spec/FIX-1430/PLAN.md Resolved
Comment thread spec/FIX-1430/DECISIONS.md Resolved

**What being wrong costs.** Narrow when it was wide: the epic wraps on a claim narrower than it reads, and someone builds the wide check afterwards — a few days, nothing already built thrown away. Wide when it was narrow: the gate is slow and intermittently red from the day it lands, which is worse because it is permanent.

**Settled: none.** No claim here has been argued twice.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spec gate · Q1. Recommendation is already narrow; “Settled: none” leaves the exit gate one implementation choice away from devforce economics (×4 harness). I’d close this at spec review as narrow + small worker artifacts and reflect that in SPEC sign-off so VG can’t widen silently.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Half accepted, and the half I am declining is the one that is not mine to take.

Not closing Q1 here. It is the product owner's call and it is with him now. Closing it at spec review would be an agent settling a scope question about what the epic's exit gate means, which is the kind of decision the gate exists to put in front of a person. Settled: none stays accurate — no claim here has been argued twice, which is the bar for a settlement.

Accepting the thing underneath it. Your actual worry is that the exit gate sits one implementation choice away from devforce economics while the question is open, and that is fair — an open question is not a licence to widen. So the narrow shape is now a hard requirement of the plan rather than a recommendation waiting on an answer: stub worker handlers doing small deterministic work, one model surface (the coordinator only), pentest-style poll and timeout fixtures. It is a guardrail with a because, not a note.

DECISIONS.md records this under Q1 explicitly — what is fenced while the owner decides, and that if the answer comes back wide, that is a change to make then, deliberately and with the cost visible. Not a door left open now.

So VG cannot widen silently, which is what you were protecting. It just does not cost the owner his question. Leaving this open since it tracks a live gate.


Generated by Claude Code

Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved
Comment thread spec/FIX-1430/SPEC.md
- **The nested cascade** — personal boards, request boards, a row that fans into rows. This issue's *other* half, phase-2 inside W4 and off this gate.
- **Which package format a capability arrives in.** FIX-1394 settles it; this lab authors no new one ([ER-2](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)).

## Sign off

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sign-off #2 (D2) is the load-bearing fork — agreed. Open Q1 alongside three closed decisions makes the PO re-derive worker realism; if narrow wins, fold Q1 into sign-off as a fourth closed line (“workers prove routing with small artifacts; harness stays in devforce-lab”).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed on D2 being the load-bearing fork — that is why it is named as the one to weigh.

Declining the conditional, though, for the same reason as the thread on DECISIONS.md:82: it is premised on "if narrow wins", and narrow winning is the owner's call to make, not one to pre-fold into the sign-off surface. Folding Q1 in as a fourth closed line would present a settled decision where there is an open question.

On the re-derivation cost you are pointing at: that is real, and it is handled where the question lives rather than by closing it. Q1 in DECISIONS.md is written to the six-part shape — plain terms, trade-off, recommendation, what would change my mind, what being wrong costs — so the owner is reading a decision rather than reconstructing one. And the narrow shape is now a binding guardrail in PLAN.md while the question is open, so the implementation cannot drift toward the wide reading while he decides.

SPEC.md still carries **Open: one** pointing at it, which is what the template prescribes for a live fork. Leaving this open alongside the Q1 thread.


Generated by Claude Code

Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved
Comment thread spec/FIX-1430/PLAN.md Resolved
Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved

Copy link
Copy Markdown
Collaborator Author

Second-look review

Verdict: appropriately scoped. Ran a second-look pass over the spec set (SPEC.md, DECISIONS.md, BUSINESS-RULES.md, PLAN.md), sized against the two existing goals/*-lab precedents (devforce-lab ~2,600 lines, pentest-lab ~3,400 lines) for a lab of comparable shape. No candidate cleared the calibration gate — everything that looked like potential scope creep turned out to be either a documented, deliberate decision already defended in DECISIONS.md/BUSINESS-RULES.md, or too small on its own to be worth a note:

  • D3 / S8 (running the lab twice, at two drain widths) — reads like creep past the stated exit gate (ER-20/21), but the epic PR (spec(epic): W4 — work reaches a seat (FIX-1407) #1905) names exactly this lab as what settles the drain-width policy wall it parked from FIX-1408, and the spec is upfront about the extra cost ("two runs where one would do... on purpose").
  • S5 (twin refusal trees for BR-2/BR-3) — could look like re-testing a fence already covered generically (custom-tools-seat.test.ts), but the marginal cost of the twin is low and it matches this codebase's existing twin+corrected-pair test convention.
  • D2 (a new goal check instead of reusing FIX-1385's) — the fork the spec itself flags as the one to weigh. Checked FIX-1385's BUSINESS-RULES.md directly: its check proves one filer → one seat that claims; this spec additionally proves a coordinator assigning by name across three seats with a row queueing behind a busy one. Real behavioral delta, not a rerun with an extra seat.
  • BR-9 (coordinator settling a row it never claimed) — possible overlap with task-tools-ownership.test.ts, but that suite's unguarded case is the patch path (updateTask/assignTask), not the transition path (completeTask) this exercises; even if overlapping, it's a single assertion inside an already-necessary run.

improve-codebase-architecture

Skipped — this PR adds only spec documents and figures under spec/FIX-1430/; nothing under packages/, apps/, or goals/ changes yet. There's no code diff to refactor or deepen against, so an architecture pass would have nothing to anchor to here. Worth re-running once the implementation PR for this issue lands.

No changes requested.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c51400d02

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved
Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved
Comment thread spec/FIX-1430/SPEC.md
@@ -0,0 +1,75 @@
# FIX-1430 · Manager-queue lab — the proof that work reaches a seat

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Lead the spec with the problem

The spec opens with an issue reference/title and then metadata before reaching the audience's current problem at line 7. Specs are explicitly covered by the repository's human-artifact rule, which requires the problem to appear first and says that no reference or label may precede it; move the problem framing above this metadata.

AGENTS.md reference: AGENTS.md:L221-L225

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not folding this one. I checked both artifacts before ruling, and the rule you are citing carves this out explicitly.

writing-for-humans.md exempts it in as many words. The sentence you are quoting continues past where the rule is usually summarised (lines 37-41):

The problem — what hurt, in the reader's terms. Nothing that follows can be judged without it, so nothing precedes it: not a ref, not a label, not a status, not what kind of artifact this is, and not the derivation that produced it. Structural navigation is not content and is exempt — a document title and the section heading the problem sits under are how a reader finds it, not something they have to read past.

The H1 and the nav line are structural navigation. The nav line is there so a reader landing from a review thread or a Linear link can reach the other three documents without climbing to the directory.

And spec-template.md mandates both, positionally. It is canonical for a spec document's own shape: the nav line is "the third line of every file, so the verify block can check for it", and the SPEC.md section lists the header line as item 1 and the people table as item 2. Its worked example (FIX-775) has exactly this order — H1, nav line, Feature · engine + client · medium · 1 PR · no epic, then ## Three people, before and after.

That people table is the problem statement: the template calls it "the spec's problem statement and its solution statement at once." So the problem does lead the body.

Two further reasons not to change it here even if the call were closer: all four W4 specs share this shape, so changing one makes it the odd document out and costs a reader the consistency the nav line exists to provide; and per the repo's authority hierarchy the more specific reference wins, which for a spec document's headings is the template.

Leaving this open rather than resolving it, in case anyone wants to push back on the reading.


Generated by Claude Code

Comment thread spec/FIX-1430/SPEC.md
- **The nested cascade** — personal boards, request boards, a row that fans into rows. This issue's *other* half, phase-2 inside W4 and off this gate.
- **Which package format a capability arrives in.** FIX-1394 settles it; this lab authors no new one ([ER-2](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)).

## Sign off

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Put the open decision first under the required heading

This sign-off section presents three ratifications before the one genuinely open product decision at line 75 and uses Sign off rather than the required Need your sign-off heading. That makes the reviewer work through settled material before the hardest ask; put Q1 first under the prescribed heading and separate or demote the confirmations.

AGENTS.md reference: AGENTS.md:L58-L62

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not folding either half of this. Wrong artifact governs, and the ordering is the template's.

The heading. AGENTS.md:58-62 is the section on asking the user for a decision, and the sentence carrying Need your sign-off scopes itself: "This applies in conversation as much as in artifacts. Batch a turn's asks under one Need your sign-off heading, numbered, hardest first." A turn is a conversation turn. What is universal there is the six-part shape of an ask, not that literal heading string.

For the document, spec-template.md is canonical, and it prescribes ## Sign off — both in its instruction ("Then Sign off: the decisions, numbered, hardest first") and twice in its worked examples, as a literal ## Sign off heading.

The ordering. The template also fixes where the open fork goes, and it is last, not first: item 6 is "the numbered decisions as one-liners linking to their cards, each with If wrong:, and the one to weigh named. Open: none, or the live forks named." This spec does exactly that — three numbered decisions, the one to weigh called out by number, then **Open: one** pointing at Q1.

I think the ordering is also right on its own merits, though the template settles it either way. The three ratifications are short one-liners; Q1 is the long one and it is stated in full in DECISIONS.md, where the six parts live. Leading the section with the hardest ask and then following it with three lines that read as trailing detail inverts the density.

Q1 itself stays open and stays with the product owner — see the reply on DECISIONS.md:82 for what was fenced underneath it. Leaving this thread open for pushback.


Generated by Claude Code

Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved
Comment thread spec/FIX-1430/BUSINESS-RULES.md Resolved
…ervational

Folds spec-level findings from Cursor, Greptile and Codex.

- BR-4's negative control could not fail: it mutated the caller-supplied
  assignee-to-seat map, which PLAN declared the sole authority, so repointing
  it moved the correct destination along with the routing. The expected
  association is now held out in the tree (each worker seat's file names the
  assignee it answers for) while the host's map stays the implementation
  under test, and VG states the red state it produces.

- BR-6 required a busy seat's second row to read `pending`. A hand-off claims
  a row before its child starts and leaves it `in_progress`
  (docs/architecture/dispatched-work.md, "The claim gate and the fence
  ticket"), so that reading is not guaranteed — and requiring it also settled
  the busy-seat policy D3 says this lab must only show. BR-6 now requires what
  holds at every drain width (nothing re-routes, nothing drops, the assignee
  is held) and records the status instead.

- D3 dissolved: "shown, not chosen" means the lab is wired to run at either
  width from one switch, not that this issue's CI runs the queue twice. S8/V5
  come off the merge bar; the two-width comparison lands when the epic asks.

- PLAN pins assignee `eligibility` on every drain's claim. ClaimOptions
  narrows candidates before the CAS flip; omit it and a drain claims a row
  addressed to another seat, keyedRouter misses, and recordError settles the
  row `errored`.

- Queued is the substrate's admission predicate, not `pending` alone, so an
  in_progress row with a lapsed lease is no longer in no column at all. The
  claim gate refuses adoption past the lease, so queued is where it belongs.
  Figure and alt text redrawn to match.

- A missing tool grant is not hire-fatal: `tools:` grants use, so a seat that
  omits it hires cleanly and fails at filing. Taxonomy corrected, BR-2 kept.

- The diff gate now rejects goals/devforce-lab/ — a behavioural suite cannot
  prove a tree unchanged.

Q1 stays open and stays the owner's. The narrow shape it would pick is now a
hard requirement of the plan so the gate cannot widen while it is open.

Two SPEC-layout findings refuted and left open: spec-template.md governs a
spec document's headings, and writing-for-humans.md exempts structural
navigation from "nothing precedes the problem".

Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T

Copy link
Copy Markdown
Collaborator Author

Round 1 folded — and one ratified line changed

Three reviewers landed within two minutes and converged. 16 threads: 12 folded and resolved, 4 left open (two refutations, two on Q1). Head is now 50af21c0.

Read this before signing off: sign-off line 3 changed. The PR body above still has the pre-round wording. SPEC.md is the current copy.

D3 · What a busy seat does is shown, not chosen: the lab is wired to run at either drain width, and the comparison goes to the epic when it asks for it.

It used to say "the same queue runs twice." The decision is unchanged — this lab still may not settle the busy-seat policy — but the work it implies moved: the two-width comparison comes off this issue's merge bar and lands as ER-15 evidence when the epic asks. One runnable queue ships here, plus the switch and a stated way to run it. D1 and D2 are untouched, and Q1 is still open and still yours.

What moved, above the fold

  • The negative control on the exit gate could not fail. BR-4's control mutated the caller-supplied assignee-to-seat map, which PLAN.md declared the sole authority for the association — so repointing it moved the correct destination along with the routing, and the check stayed green. The expected pairing is now held out in the tree (each worker seat's file names the assignee it answers for) while the map stays the implementation under test, and VG states the red state it produces.
  • A routing risk verified in landed code, not taken on a reviewer's word. A per-seat drain that claims without narrowing will claim another seat's row, miss in the router, and settle that row errored — worse than the mis-route that was reported. The remedy already exists as a first-class option (ClaimOptions.eligibility narrows candidates before the CAS flip), so the design stands; PLAN.md now pins it as a guardrail instead of leaving it implicit.
  • BR-6 no longer requires the waiting row to read pending. A hand-off claims a row before its child starts and leaves it in_progress, so that reading was not guaranteed — and requiring it was quietly choosing one of the two busy-seat policies D3 says this lab may only show.
  • A recoverable row was in no queue column at all. Queued is now the substrate's own admission predicate rather than pending alone; figure and alt text redrawn to match.
  • Smaller: the failure taxonomy contradicted BR-2 on when a missing tool grant bites (taxonomy was wrong); the diff gate now also rejects goals/devforce-lab/.

Left open, on purpose

  • Q1 — two reviewers asked me to close it as narrow. Declined: it is yours. What I did instead is fence it, so the gate cannot widen toward devforce economics while you decide — the narrow shape (stub worker handlers, one model surface, poll/timeout fixtures) is now a hard requirement of the plan rather than a recommendation waiting on your answer. If you answer wide, that is a change to make then, priced visibly.
  • Two spec-layout findings refuted — that SPEC.md must lead with the problem ahead of its nav line, and that its sign-off section must use the Need your sign-off heading. spec-template.md is canonical for a spec document's headings and prescribes exactly this shape; writing-for-humans.md exempts structural navigation from "nothing precedes the problem" in as many words. Worth noting the two artifacts are not in conflict here: this PR body does use Need your sign-off, because a PR body is where that heading belongs. Threads left open for pushback.

Outstanding

  • Linear was not mirrored. api.linear.app returns 403 at this environment's network policy, so FIX-1430 still carries the pre-round spec. Needs a mirror from an environment with Linear reach before the durable copy is current.
  • All four documents are over the template's word budgets (SPEC +87, BUSINESS-RULES +487, DECISIONS +576, PLAN +1147 prose words). Reporting rather than cutting: most of the overage predates this round, and trimming it would mean deleting substance three reviewers asked for. One duplicate diagram was cut.

No labels applied, nothing merged or closed, nothing outside spec/FIX-1430/.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — ack on Round 1 fold at 50af21c0.

Not owner approval / not the gate. Shared jhoffner login looks like Jake; product sign-off on Q1 / D1–D3 stays with Jake (and PM on kill/over-scope).

D3 wording — coherent with ER-15

The ratified line change is the right split:

  • Decision unchanged: this lab may not settle busy-seat / drain-width policy inside goals/.
  • Work moved: two-width comparison is off this issue's merge bar and becomes ER-15 evidence when the epic asks. One runnable queue + the switch + a documented way to run either width is the right deliverable here.

My earlier stamp's "show both busy-seat widths" should be read that way — wired for both, not CI-required twice on FIX-1430. The rejected edge "run both widths in this issue's CI" in DECISIONS.md matches.

BR-6 dropping the pending requirement is the same fence: requiring that status would have quietly picked one of the two policies D3 forbids choosing here.

Still holding

  • D1 / D2 untouched and still the right bars (lab-local columns; queue ≠ hand-off).
  • Q1 stays Jake's. Narrow-as-plan-hard-requirement while open is a good fence; widening later is a priced change, not a silent door.
  • ClaimOptions.eligibility as an explicit PLAN guardrail closes the per-seat drain mis-claim risk without inventing a new substrate path.

No new two-direction fork vs #1905 / siblings. Linear mirror gap noted — durable copy lag only, not a coherence fork.

— FSD Architect

@jhoffner jhoffner added the spec label Sep 19, 2026
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Approved

@jhoffner jhoffner added the spec approved This spec is ready for implementation label Sep 19, 2026
Both rules the epic's exit gate (ER-20) is measured by were written
against an earlier reading of FIX-1385's surface and could not fail.

BR-2 graded a `tools:` line on the coordinator's own file. The task
tools are capability *controls* — `createTaskToolsCapability` puts them
in the fence-exempt `controlTools` bucket, and core never intersects
that bucket with a block's declared `tools:`. The twin tree that omitted
the line would have filed just as happily. BR-2 now grades what does
grant: composing the capability on the kind. Three arms, one of which is
the tripwire — the real coordinator holds all eight *despite*
`tools: []` in its file, so routing the eight through the catalog door
instead turns the rule red.

Which door, stated: the capability door FIX-1385 ships for models, not
an app catalog registering `buildTaskToolsList()` where `tools:` does
bite. Proving the catalog door would make ER-20 evidence for a wiring
nothing else uses. The four-tool narrowing is gone with it — selecting
among the eight is capability selection, parked on the epic under ER-15.

BR-8 graded a membership gate the filing path does not have. `author` is
optional, caller-supplied and stored `authorVerified: false`, and
`addTask` — the door the coordinator files through — carries no `author`
at all. BR-8 now names the action that has the check, says it proves a
label check rather than authentication, and grades the no-author call
landing beside the refusal. "Fence" is gone from DECISIONS.

No approved decision reopened. D2's heading loses "the tools it
declared" the way FIX-1385's D3 did: the reasoning was wrong, the choice
was not.

Verified at source: packages/orchestration/src/skills/
task-tools-capability.ts:795-802, packages/core/src/capability/
types.ts:99-121, packages/core/src/blocks/generator.ts:2760-2816,
packages/orchestration/src/skills/library.ts:680-700,
packages/workforce/src/channel/channel-flow.ts:162-171, and
FIX-1385's SPEC.md:16/76, BR-10/BR-17/BR-20, DECISIONS D3 + V3/V4.

Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T

Copy link
Copy Markdown
Collaborator Author

Two graded rules could not go red — both corrected (bbacbe3)

Both were rules ER-20 is measured by, and both were written against an earlier reading of FIX-1385's surface. Folded as corrections of fact. No approved decision reopened — D2's choice stands; only its heading lost wording that described a mechanism that does not exist.

BR-2 — tools: could neither grant nor withhold the task tools

Verified in the landed code before folding:

  • createTaskToolsCapability contributes the eight through controlTools, not tools — packages/orchestration/src/skills/task-tools-capability.ts:795-802.
  • controlTools is the fence-exempt bucket by contract: "Tools that are NOT subject to a consuming block's tools: fence" — packages/core/src/capability/types.ts:99-121.
  • The generator never intersects that bucket with a declared tools:; it concatenates it unconditionally, and only the catalog bucket is dropped behind a raised fence — packages/core/src/blocks/generator.ts:2760-2816.
  • The skills library's delegation path does the same: buildTaskToolsList(...) lands in contributions.controlTools — packages/orchestration/src/skills/library.ts:680-700.
  • packages/workforce/src/agent-worker-flow.ts:223 states it outright: "A capability's controlTools are exempt by design."

So the twin tree that omitted the line would have filed successfully too, and the rule graded nothing. FIX-1385's BR-17 says the same, and its DECISIONS records carrying this spec's exact sentence in its own draft and having it refuted in round 1.

What BR-2 grades now: composing the capability on the kind. Three arms — the real coordinator holds all eight; the same coordinator still holds all eight with tools: [] in its own seat file; a twin kind composing nothing holds none and never writes the ledger. The middle arm is the tripwire: wire the eight as catalog tools and it goes red.

Which door, and why. The capability door — the one FIX-1385 ships for models. The catalog door is real (an app registering buildTaskToolsList() output, where tools: genuinely bites), but proving it would make the epic's exit gate evidence for a wiring nothing else uses, while leaving the shipped door unexercised. Recorded in DECISIONS → Decided, not asked, with a guardrail in PLAN so the implementer cannot drift into it by accident.

The four-tool narrowing is gone. Selecting among the eight is the capability-selection question FIX-1385 parked under ER-15; this lab may not settle it, and controlTools is all-eight-or-none anyway.

SPEC.md now also says plainly that the board grant is still code in the kind, even though the board's existence is one line in the channel file. That edge was being blurred by the old diff block.

BR-8 — graded a door the lab does not use

FIX-1385 SPEC.md:16 and :76 say filing is not members-only; its BR-10 pins that a row with no author goes through, and BR-20 that addTask carries no author at all. Confirmed in code: packages/workforce/src/channel/channel-flow.ts:162-171 — if (input.author !== undefined && !channel.members.includes(input.author)), with the module's own comment "A validity check against the declared roster, NOT authentication", stored authorVerified: false. And addTask's input schema has no author field at all (task-tools-capability.ts, the addTask definition).

So no check ran on the door the coordinator actually files through.

What BR-8 grades now: the channel's own file action, carrying an explicit non-roster author. It says in the rule that this proves a label check, not authentication, that the same call with no author lands, and that addTask is unchecked. Both arms are graded — drop the second and the rule goes green against a path that checks nothing, which is what it did before. The word fence is gone from DECISIONS.

Also added

PLAN.md → What turns each corrected check red, naming the red state for each of the two, since a rule the exit gate is measured by that cannot go red is worse than no rule. S5 no longer files BR-2's twin under the refusal trees — it refuses nowhere; it is a second kind built beside the real one.

Nothing refused. Both findings held at the source.


Generated by Claude Code

jhoffner pushed a commit that referenced this pull request Sep 19, 2026
…ER-19 (FIX-1407)

A cross-spec pass over the children's own documents found this epic asserting
three things they had since narrowed or dropped. Each was checked against the
child's text before folding; the child won on substance each time. None reopens
an approved decision.

1. The inventory -> boards sequencing edge does not exist. FIX-1385's SPEC,
   DECISIONS and BUSINESS-RULES name FIX-1405 and "inventory" zero times; its
   PLAN's two mentions are an optional read and a collision note, and its BR-7
   carries the caller's assignee with no seat resolution. The set's one blocking
   edge is FIX-1385's implementation before FIX-1430. Redrawn in the graph, the
   path figure's gutter, the plan's unblocks list and the entails table. What
   replaces it is a merge order: FIX-1385's PR-A lands before FIX-1405's PR-B,
   since both edit the channel flow factory and the binder.

2. ER-2 now binds whatever FIX-1394's ratify records, "don't collapse" included
   (its BR-16 makes that a result with the same force). The end-state box reads
   as a question; the four-teams row, the set table and the ownership matrix
   follow.

3. ER-19 is a check over this set's own diff, not a repo-wide rename —
   FIX-1385's BR-14 scopes it to the vocabulary this issue mints, citing project
   PD-4. The repo-wide pass stays the project's with no owner inside W4, named
   out so the wrap cannot close by confirming a pass nobody ran.

Also refreshed from verified PR state: the set table carries the four child spec
PRs, FIX-1385 (#1917) and FIX-1430 (#1919) are spec approved, FIX-1394 (#1915)
and FIX-1405 (#1916) are in review.

All three figures re-rendered and reviewed in both themes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
@jhoffner jhoffner closed this Sep 19, 2026
jhoffner pushed a commit that referenced this pull request Sep 19, 2026
…on (FIX-1407)

Re-derived from GitHub, not relayed. What moved since the table was written:

- #1915 (FIX-1394), #1916 (FIX-1405), #1917 (FIX-1385), #1919 (FIX-1430) are
  all CLOSED UNMERGED carrying `spec approved`. Their spec/* branches survive.
- #1920 (FIX-1405 PR-A) merged.
- #1921 (FIX-1394 matrix, spec/FIX-1394-matrix) open and never merges — the
  ratify decision is with the owner.
- #1922 (FIX-1385) open, review round 1 folded at 73dabbb, head 03f25f9.
- #1923 (FIX-1405 S4) open, round 1 at bbf41ad plus two docs commits.
- FIX-1430 build not started; FIX-817 unclaimed.

No row still reads "spec in review" — that was stale on two rows and wrong in
the other direction on two more, which had moved past approval into build.

ER-16 said "a child's Linear state is mirrored the moment it changes". It is
not. api.linear.app is unreachable from every session on this epic (403 at the
egress proxy) and ~8 status writes are queued. Since our convention hands the
durable copy to Linear the moment a spec PR closes, the durable copy of four
approved specs is currently a git branch. ER-16, the set table and PLAN's
"Where it is" now say that plainly instead of implying the tracker is current.
ER-16 also names the consequence for the wrap term, which requires every child
to be Linear-terminal and so cannot be satisfied while the writes are queued.

The path figure is redrawn: a new `.impl` bar class, per-lane bars for the two
implementing children and the merged PR-A segment, FIX-1430 reduced to a dashed
not-started lane, and the legend regrouped. Both alt texts rewritten. Rendered
and read in light and dark; bars align to the axis, nothing overflows.

Dependency graph unchanged — no issue in the set became done, so no border or
placeholder moved.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

spec approved This spec is ready for implementation spec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants